Net::SNMP - Object oriented interface to SNMP |
session()
- create a new Net::SNMP objectclose()
- clear the Transport Layer associated with the objectsnmp_dispatcher()
- enter the non-blocking object event loopget_request()
- send a SNMP get-request to the remote agentget_next_request()
- send a SNMP get-next-request to the remote agentset_request()
- send a SNMP set-request to the remote agenttrap()
- send a SNMP trap to the remote managerget_bulk_request()
- send a get-bulk-request to the remote agentinform_request()
- send an inform-request to the remote managersnmpv2_trap()
- send a snmpV2-trap to the remote managerget_table()
- retrieve a table from the remote agentversion()
- get the SNMP version from the objecterror()
- get the current error message from the objecthostname()
- get the hostname associated with the objecterror_status()
- get the current SNMP error-status from the objecterror_index()
- get the current SNMP error-index from the objectvar_bind_list()
- get the hash reference to the last SNMP responsetimeout()
- set or get the current timeout period for the objectretries()
- set or get the current retry count for the objectmax_msg_size()
- set or get the current maxMsgSize for the objecttranslate()
- enable or disable the translation mode for the objectdebug()
- set or get the debug mode for the moduleoid_base_match()
- determine if an OID has a specified OID baseoid_lex_sort()
- sort a list of OBJECT IDENTIFIERs lexicographicallyticks_to_time()
- convert TimeTicks to formatted time
Net::SNMP - Object oriented interface to SNMP
The Net::SNMP module implements an object oriented interface to the Simple Network Management Protocol. Perl applications can use the module to retrieve or update information on a remote host using the SNMP protocol. The module supports SNMP version-1, SNMP version-2c (Community-Based SNMPv2), and SNMP version-3. The Net::SNMP module assumes that the user has a basic understanding of the Simple Network Management Protocol and related network management concepts.
The Net::SNMP module abstracts the intricate details of the Simple Network Management Protocol by providing a high level programming interface to the protocol. Each Net::SNMP object provides a one-to-one mapping between a Perl object and a remote SNMP agent or manager. Once an object is created, it can be used to perform the basic protocol exchange actions defined by SNMP.
A Net::SNMP object can be created such that it has either ``blocking'' or ``non-blocking'' properties. By default, the methods used to send SNMP messages do not return until the protocol exchange has completed successfully or a timeout period has expired. This behavior gives the object a ``blocking'' property because the flow of the code is stopped until the method returns.
The optional named argument -nonblocking can be passed to the object
constructor with a true value to give the object ``non-blocking'' behavior.
A method invoked by a non-blocking object queues the SNMP message and returns
immediately, allowing the flow of the code to continue. The queued SNMP
messages are not sent until an event loop is entered by calling the
snmp_dispatcher()
method. When the SNMP messages are sent, any response to
the messages invokes the subroutine defined by the user when the message was
originally queued. The event loop exits when all messages have been removed
from the queue by either receiving a response, or by exceeding the number of
retries at the Transport Layer.
The default behavior of the methods associated with a Net::SNMP object is to
block the code flow until the method completes. For methods that initiate a
SNMP protocol exchange requiring a response, a hash reference containing the
results of the query is returned. The undefined value is returned by all
methods when a failure has occurred. The error()
method can be used to
determine the cause of the failure.
The hash reference returned by a SNMP protocol exchange points to a hash
constructed from the VarBindList contained in the SNMP response message. The
hash is created using the ObjectName and the ObjectSyntax pairs in the
VarBindList. The keys of the hash consist of the OBJECT IDENTIFIERs in dotted
notation corresponding to each ObjectName in the VarBindList. The value of
each hash entry is set equal to the value of the corresponding ObjectSyntax.
This hash reference can also be retrieved using the var_bind_list()
method.
When a Net::SNMP object is created having non-blocking behavior, the invocation
of a method associated with the object returns immediately, allowing the flow
of the code to continue. When a method is invoked that would initiate a SNMP
protocol exchange requiring a response, either a true value (i.e. 0x1) is
returned immediately or the undefined value is returned if there was a failure.
The error()
method can be used to determine the cause of the failure.
The contents of the VarBindList contained in the SNMP response message can be
retrieved by calling the var_bind_list()
method using the object reference
passed as the first argument to the callback. The value returned by the
var_bind_list()
method is a hash reference created using the ObjectName and
the ObjectSyntax pairs in the VarBindList. The keys of the hash consist of
the OBJECT IDENTIFIERs in dotted notation corresponding to each ObjectName
in the VarBindList. The value of each hash entry is set equal to the value of
the corresponding ObjectSyntax. The undefined value is returned if there has
been a failure and the error()
method may be used to determine the reason.
When named arguments are expected by the methods, two different styles are supported. All examples in this documentation use the dashed-option style:
$object->method(-argument => $value);
However, the IO:: style is also allowed:
$object->method(Argument => $value);
When the -callback argument only contains a subroutine reference, the subroutine is evaluated passing a reference to the original Net::SNMP object as the only parameter. If the -callback argument was defined as an array reference, all elements in the array are passed to subroutine after the reference to the Net::SNMP object. The first element, which is required to be a reference to a subroutine, is removed before the remaining arguments are passed to that subroutine.
Once one method is invoked with the -callback argument, this argument stays with the object and is used by any further calls to methods using the -callback option if the argument is absent. The undefined value may be passed to the -callback argument to delete the callback.
NOTE: The subroutine being passed with the -callback named argument should not cause blocking itself. This will cause all the actions in the event loop to be stopped, defeating the non-blocking property of the Net::SNMP module.
session()
- create a new Net::SNMP object($session, $error) = Net::SNMP->session( [-hostname => $hostname,] [-port => $port,] [-localaddr => $localaddr,] [-localport => $localport,] [-nonblocking => $boolean,] [-version => $version,] [-timeout => $seconds,] [-retries => $count,] [-maxmsgsize => $octets,] [-translate => $translate,] [-debug => $debugmask,] [-community => $community,] # v1/v2c [-username => $username,] # v3 [-authkey => $authkey,] # v3 [-authpassword => $authpasswd,] # v3 [-authprotocol => $protocol,] # v3 [-privkey => $privkey,] # v3 [-privpassword => $privpasswd,] # v3 );
This is the constructor for Net::SNMP objects. In scalar context, a reference to a new Net::SNMP object is returned if the creation of the object is successful. In list context, a reference to a new Net::SNMP object and an empty error message string is returned. If a failure occurs, the object reference is returned as the undefined value. The error string may be used to determine the cause of the error.
Most of the named arguments passed to the constructor define basic attributes for the object and are not modifiable after the object has been created. The -timeout, -retries, -maxmsgsize, -translate, and -debug arguments are modifiable using an accessor method. See their corresponding method definitions for a complete description of their usage, default values, and valid ranges.
By default, the source IP address and port number are assigned dynamically by the local device on which the Net::SNMP module is being used. This dynamic assignment can be overridden by using the -localaddr and -localport arguments. These values default to INADDR_ANY (typically 0.0.0.0) and 0 respectively. The -localaddr argument will accept either an IP network hostname or an IP address in dotted notation. If a hostname is specified, the resolved IP address must be a valid address on the local device.
session()
constructor. The Net::SNMP module supports
SNMPv1, SNMPv2c, and SNMPv3. The module defaults to SNMPv1 if no -version
argument is specified. The -version argument expects either a digit (i.e.
'1', '2', or '3') or a string specifying the version (i.e. 'snmpv1',
'snmpv2c', or 'snmpv3') to define the SNMP version.
The Security Model used by the Net::SNMP object is based on the SNMP version associated with the object. If the SNMP version is SNMPv1 or SNMPv2c a Community-based Security Model will be used, while the User-based Security Model (USM) will be used if the version is SNMPv3.
The SNMPv3 User-based Security model (USM) allows different levels of security which address authentication and privacy concerns. A SNMPv3 Net::SNMP object will derive the security level (securityLevel) based on which of the following arguments are specified.
By default a securityLevel of 'noAuthNoPriv' is assumed. If the -authkey
or -authpassword arguments are specified, the securityLevel becomes
'authNoPriv'. The -authpassword argument expects a string which is 1 to
32 bytes in length. Optionally, the -authkey argument can be used so that
a plain text password does not have to be specified in a script. The
-authkey argument expects a hexadecimal string produced by localizing the
password with the authoritativeEngineID for the specific destination device.
The snmpkey
utility included with the distribution can be used to create
the hexadecimal string (see the snmpkey manpage).
Two different hash algorithms are defined by SNMPv3 which can be used by the Security Model for authentication. These algorithms are MD5 (RFC 1321) and SHA-1 (NIST FIPS PUB 180). The default algorithm used by the module is MD5. This behavior can be changed by using the -authprotocol argument. This argument expects either the string 'md5' or 'sha1' to be passed to modify the hash algorithm.
By specifying the arguments -privkey or -privpassword the securityLevel associated with the object becomes 'authPriv'. According to SNMPv3, privacy requires the use of authentication. Therefore, if either of these two arguments are present and the -authkey or -authpassword arguments are missing, the creation of the object fails. The -privkey and -privpassword arguments expect the same input as the -authkey and -authpassword arguments respectively.
close()
- clear the Transport Layer associated with the object$session->close;
This method clears the UDP Transport Layer and any errors associated with the object. Once closed, the Net::SNMP object can no longer be used to send or receive SNMP messages.
snmp_dispatcher()
- enter the non-blocking object event loop$session->snmp_dispatcher();
This method enters the event loop associated with non-blocking Net::SNMP
objects. The method exits when all queued SNMP messages have received a
response or have timed out at the Transport Layer. This method is also
exported as the stand alone function snmp_dispatcher()
by default
(see EXPORTS).
get_request()
- send a SNMP get-request to the remote agent$result = $session->get_request( [-callback => sub {},] # non-blocking [-delay => $seconds,] # non-blocking [-contextengineid => $engine_id,] # v3 [-contextname => $name,] # v3 -varbindlist => \@oids, );
This method performs a SNMP get-request query to gather data from the remote agent on the host associated with the Net::SNMP object. The message is built using the list of OBJECT IDENTIFIERs in dotted notation passed to the method as an array reference using the -varbindlist argument. Each OBJECT IDENTIFER is placed into a single SNMP GetRequest-PDU in the same order that it held in the original list.
A reference to a hash is returned in blocking mode which contains the contents
of the VarBindList. In non-blocking mode, a true value is returned when no
error has occurred. In either mode, the undefined value is returned when an
error has occurred. The error()
method may be used to determine the cause
of the failure.
get_next_request()
- send a SNMP get-next-request to the remote agent$result = $session->get_next_request( [-callback => sub {},] # non-blocking [-delay => $seconds,] # non-blocking [-contextengineid => $engine_id,] # v3 [-contextname => $name,] # v3 -varbindlist => \@oids, );
This method performs a SNMP get-next-request query to gather data from the remote agent on the host associated with the Net::SNMP object. The message is built using the list of OBJECT IDENTIFIERs in dotted notation passed to the method as an array reference using the -varbindlist argument. Each OBJECT IDENTIFER is placed into a single SNMP GetNextRequest-PDU in the same order that it held in the original list.
A reference to a hash is returned in blocking mode which contains the contents
of the VarBindList. In non-blocking mode, a true value is returned when no
error has occurred. In either mode the undefined value is returned when an
error has occurred. The error()
method may be used to determine the cause
of the failure.
set_request()
- send a SNMP set-request to the remote agent$result = $session->set_request( [-callback => sub {},] # non-blocking [-delay => $seconds,] # non-blocking [-contextengineid => $engine_id,] # v3 [-contextname => $name,] # v3 -varbindlist => \@oid_value, );
This method is used to modify data on the remote agent that is associated with the Net::SNMP object using a SNMP set-request. The message is built using a list of values consisting of groups of an OBJECT IDENTIFIER, an object type, and the actual value to be set. This list is passed to the method as an array reference using the -varbindlist argument. The OBJECT IDENTIFIERs in each trio are to be in dotted notation. The object type is a byte corresponding to the ASN.1 type of value that is to be set. Each of the supported ASN.1 types have been defined and are exported by the package by default (see EXPORTS).
A reference to a hash is returned in blocking mode which contains the contents
of the VarBindList. In non-blocking mode, a true value is returned when no
error has occurred. In either mode the undefined value is returned when an
error has occurred. The error()
method may be used to determine the cause
of the failure.
trap()
- send a SNMP trap to the remote manager$result = $session->trap( [-delay => $seconds,] # non-blocking [-enterprise => $oid,] [-agentaddr => $ipaddress,] [-generictrap => $generic,] [-specifictrap => $specific,] [-timestamp => $timeticks,] -varbindlist => \@oid_value, );
This method sends a SNMP trap to the remote manager associated with the Net::SNMP object. All arguments are optional and will be given the following defaults in the absence of a corresponding named argument:
set_request()
method.
The OBJECT IDENTIFIERs in each trio are to be in dotted notation. The object
type is a byte corresponding to the ASN.1 type for the value. Each of the
supported types have been defined and are exported by default (see
EXPORTS).
A true value is returned when the method is successful. The undefined value
is returned when a failure has occurred. The error()
method can be used to
determine the cause of the failure. Since there are no acknowledgements for
Trap-PDUs, there is no way to determine if the remote host actually received
the trap.
NOTE: When the object is in non-blocking mode, the trap is not sent until the event loop is entered and no callback is ever executed.
NOTE: This method can only be used when the version of the object is set to SNMPv1.
get_bulk_request()
- send a get-bulk-request to the remote agent$result = $session->get_bulk_request( [-callback => sub {},] # non-blocking [-delay => $seconds,] # non-blocking [-contextengineid => $engine_id,] # v3 [-contextname => $name,] # v3 [-nonrepeaters => $nonrep,] [-maxrepetitions => $maxrep,] -varbindlist => \@oids, );
This method performs a SNMP get-bulk-request query to gather data from the remote agent on the host associated with the Net::SNMP object. All arguments are optional except -varbindlist and will be given the following defaults in the absence of a corresponding named argument:
A reference to a hash is returned in blocking mode which contains the contents
of the VarBindList. In non-blocking mode, a true value is returned when no
error has occurred. In either mode the undefined value is returned when an
error has occurred. The error()
method may be used to determine the cause
of the failure.
NOTE: This method can only be used when the version of the object is set to SNMPv2c or SNMPv3.
inform_request()
- send an inform-request to the remote manager$result = $session->inform_request( [-callback => sub {},] # non-blocking [-delay => $seconds,] # non-blocking [-contextengineid => $engine_id,] # v3 [-contextname => $name,] # v3 -varbindlist => \@oid_value, );
This method is used to provide management information to the remote manager associated with the Net::SNMP object using an inform-request. The message is built using a list of values consisting of groups of an OBJECT IDENTIFIER, an object type, and the actual value to be identified. This list is passed to the method as an array reference using the -varbindlist argument. The OBJECT IDENTIFIERs in each trio are to be in dotted notation. The object type is a byte corresponding to the ASN.1 type of value that is to be identified. Each of the supported ASN.1 types have been defined and are exported by the package by default (see EXPORTS).
The first two variable-bindings fields in the inform-request are specified by SNMPv2 and should be:
A reference to a hash is returned in blocking mode which contains the contents
of the VarBindList. In non-blocking mode, a true value is returned when no
error has occurred. In either mode the undefined value is returned when an
error has occurred. The error()
method may be used to determine the cause
of the failure.
NOTE: This method can only be used when the version of the object is set to SNMPv2c or SNMPv3.
snmpv2_trap()
- send a snmpV2-trap to the remote manager$result = $session->snmpv2_trap( [-delay => $seconds,] # non-blocking -varbindlist => \@oid_value, );
This method sends a snmpV2-trap to the remote manager associated with the Net::SNMP object. The message is built using a list of values consisting of groups of an OBJECT IDENTIFIER, an object type, and the actual value to be identified. This list is passed to the method as an array reference using the -varbindlist argument. The OBJECT IDENTIFIERs in each trio are to be in dotted notation. The object type is a byte corresponding to the ASN.1 type of value that is to be identified. Each of the supported ASN.1 types have been defined and are exported by the package by default (see EXPORTS).
The first two variable-bindings fields in the snmpV2-trap are specified by SNMPv2 and should be:
A true value is returned when the method is successful. The undefined value
is returned when a failure has occurred. The error()
method can be used
to determine the cause of the failure. Since there are no acknowledgements for
SNMPv2-Trap-PDUs, there is no way to determine if the remote host actually
received the snmpV2-trap.
NOTE: When the object is in non-blocking mode, the snmpV2-trap is not sent until the event loop is entered and no callback is ever executed.
NOTE: This method can only be used when the version of the object is set to SNMPv2c. SNMPv2-Trap-PDUs are supported by SNMPv3, but require the sender of the message to be an authoritative SNMP engine which is not currently supported by the Net::SNMP module.
get_table()
- retrieve a table from the remote agent$result = $session->get_table( [-callback => sub {},] # non-blocking [-delay => $seconds,] # non-blocking [-contextengineid => $engine_id,] # v3 [-contextname => $name,] # v3 -baseoid => $oid, );
This method performs repeated SNMP get-next-request or get-bulk-request (when using SNMPv2c or SNMPv3) queries to gather data from the remote agent on the host associated with the Net::SNMP object. The first message sent is built using the OBJECT IDENTIFIER in dotted notation passed to the method by the -baseoid argument. Repeated SNMP requests are issued until the OBJECT IDENTIFER in the response is no longer a child of the base OBJECT IDENTIFIER.
A reference to a hash is returned in blocking mode which contains the contents
of the VarBindList. In non-blocking mode, a true value is returned when no
error has occurred. In either mode the undefined value is returned when an
error has occurred. The error()
method may be used to determine the cause
of the failure.
WARNING: Results from this method can become very large if the base OBJECT IDENTIFIER is close to the root of the SNMP MIB tree.
version()
- get the SNMP version from the object$rfc_version = $session->version;
This method returns the current value for the SNMP version associated with the object. The returned value is the corresponding version number defined by the RFCs for the protocol version field (i.e. SNMPv1 == 0, SNMPv2c == 1, and SNMPv3 == 3). The RFC versions are defined as constant by the module and can be exported by request (see EXPORTS).
error()
- get the current error message from the object$error_message = $session->error;
This method returns a text string explaining the reason for the last error. An empty string is returned if no error has occurred.
hostname()
- get the hostname associated with the object$hostname = $session->hostname;
This method returns the hostname string that is associated with the object
as it was passed to the session()
constructor.
error_status()
- get the current SNMP error-status from the object$error_status = $session->error_status;
This method returns the numeric value of the error-status contained in the last SNMP GetResponse-PDU received by the object.
error_index()
- get the current SNMP error-index from the object$error_index = $session->error_index;
This method returns the numeric value of the error-index contained in the last SNMP GetResponse-PDU received by the object.
var_bind_list()
- get the hash reference to the last SNMP response$response = $session->var_bind_list;
This method returns a hash reference created using the ObjectName and the
ObjectSyntax pairs in the VarBindList of the last SNMP GetResponse-PDU
received by the object. The keys of the hash consist of the OBJECT
IDENTIFIERs in dotted notation corresponding to each ObjectName in the
VarBindList. If any of the OBJECT IDENTIFIERs passed to the request method
began with a leading dot, all of the OBJECT IDENTIFIER hash keys will be
prefixed with a leading dot. The value of each hash entry is set equal to
the value of the corresponding ObjectSyntax. The undefined value is returned
if there has been a failure and the error()
method may be used to determine
the reason.
timeout()
- set or get the current timeout period for the object$seconds = $session->timeout([$seconds]);
This method returns the current value for the Transport Layer timeout for the Net::SNMP object. This value is the number of seconds that the object will wait for a response from the agent on the remote host. The default timeout is 5.0 seconds.
If a parameter is specified, the timeout for the object is set to the provided
value if it falls within the range 1.0 to 60.0 seconds. The undefined value
is returned upon an error and the error()
method may be used to determine
the cause.
retries()
- set or get the current retry count for the object$count = $session->retries([$count]);
This method returns the current value for the number of times to retry sending a SNMP message to the remote host. The default number of retries is 1.
If a parameter is specified, the number of retries for the object is set to
the provided value if it falls within the range 0 to 20. The undefined value
is returned upon an error and the error()
method may be used to determine
the cause.
max_msg_size()
- set or get the current maxMsgSize for the object$octets = $session->max_msg_size([$octets]);
This method returns the current value for the maximum message size (maxMsgSize) for the Net::SNMP object. This value is the largest message size in octets that can be prepared or processed by the object. The default maxMsgSize is 1472 octets.
If a parameter is specified, the maxMsgSize is set to the provided
value if it falls within the range 484 to 2147483647 octets. The undefined
value is returned upon an error and the error()
method may be used to
determine the cause.
NOTE: When using SNMPv3, the maxMsgSize is actually contained in the SNMP message (as msgMaxSize). If the value received from a remote device is less than the current maxMsgSize, the size is automatically adjusted to be the lower value.
translate()
- enable or disable the translation mode for the object$mask = $session->translate([ $mode | [ # Perl anonymous ARRAY reference ['-all' => $mode0,] ['-none' => $mode1,] ['-octetstring => $mode2,] ['-null' => $mode3,] ['-timeticks' => $mode4,] ['-opaque' => $mode5,] ['-nosuchobject' => $mode6,] ['-nosuchinstance' => $mode7,] ['-endofmibview' => $mode8,] ['-unsigned' => $mode9] ] ]);
When the object decodes the GetResponse-PDU that is returned in response to a SNMP message, certain values are translated into a more ``human readable'' form. By default the following translations occur:
The translate()
method can be invoked with two different types of arguments.
If the argument passed is any Perl variable type except an array reference, the translation mode for all ASN.1 types is set to either enabled or disabled, depending on the value of the passed parameter. Any value that Perl would treat as a true value will set the mode to be enabled for all types, while a false value will disable translation for all types.
A reference to an array can be passed to the translate()
method in order to
define the translation mode on a per ASN.1 type basis. The array is expected
to contain a list of named argument pairs for each ASN.1 type that is to
be modified. The arguments in the list are applied in the order that they
are passed in via the array. Arguments at the end of the list supercede
those passed earlier in the list. The argument ``-all'' can be used to specify
that the mode is to apply to all ASN.1 types. Only the arguments for the
ASN.1 types that are to be modified need to be included in the list.
The translate()
method returns a bit mask indicating which ASN.1 types
are to be translated. Definitions of the bit to ASN.1 type mappings can be
exported using the :translate tag (see EXPORTS). The undefined value
is returned upon an error and the error()
method may be used to determine
the cause.
debug()
- set or get the debug mode for the module$mask = $session->debug([$mask]);
This method is used to enable or disable debugging for the Net::SNMP module.
Debugging can be enabled on a per component level as defined by a bit mask
passed to the debug()
method. The bit mask is broken up as follows:
Symbols representing these bit mask values are defined by the module and can
be exported using the :debug tag (see EXPORTS). If a non-numeric
value is passed to the debug()
method, it is evaluated in boolean context.
Debugging for all of the components is then enabled or disabled based on the
resulting truth value.
The current debugging mask is returned by the method. Debugging can also be
enabled using the stand alone function snmp_debug()
. This function can be
exported by request (see EXPORTS).
oid_base_match()
- determine if an OID has a specified OID base$value = oid_base_match($base_oid, $oid);
This function takes two OBJECT IDENTIFIERs in dotted notation and returns a
true value (i.e. 0x1) if the second OBJECT IDENTIFIER is equal to or is a
child of the first OBJECT IDENTIFIER in the SNMP Management Information Base
(MIB). This function can be used in conjunction with the get-next-request()
or get-bulk-request()
methods to determine when a OBJECT IDENTIFIER in the
GetResponse-PDU is no longer in the desired MIB tree branch.
oid_lex_sort()
- sort a list of OBJECT IDENTIFIERs lexicographically@sorted_oids = oid_lex_sort(@oids);
This function takes a list of OBJECT IDENTIFIERs in dotted notation and returns the listed sorted in lexicographical order.
ticks_to_time()
- convert TimeTicks to formatted time$time = ticks_to_time($timeticks);
This function takes an ASN.1 TimeTicks value and returns a string representing the time defined by the value. The TimeTicks value is expected to be a non-negative integer value representing the time in hundredths of a second since some epoch. The returned string will display the time in days, hours, and seconds format according to the value of the TimeTicks argument.
The Net::SNMP module uses the Exporter module to export useful constants and subroutines. These exportable symbols are defined below and follow the rules and conventions of the Exporter module (see the Exporter manpage).
This example gets the sysUpTime from a remote host.
#! /usr/local/bin/perl
use strict;
use Net::SNMP;
my ($session, $error) = Net::SNMP->session( -hostname => shift || 'localhost', -community => shift || 'public', -port => shift || 161 );
if (!defined($session)) { printf("ERROR: %s.\n", $error); exit 1; }
my $sysUpTime = '1.3.6.1.2.1.1.3.0';
my $result = $session->get_request( -varbindlist => [$sysUpTime] );
if (!defined($result)) { printf("ERROR: %s.\n", $session->error); $session->close; exit 1; }
printf("sysUpTime for host '%s' is %s\n", $session->hostname, $result->{$sysUpTime} );
$session->close;
exit 0;
This example sets the sysContact information on the remote host to
``Help Desk x911''. The named arguments passed to the session()
constructor
are for the demonstration of syntax only. These parameters will need to be
set according to the SNMPv3 parameters of the remote host used by the script.
#! /usr/local/bin/perl
use strict;
use Net::SNMP;
my ($session, $error) = Net::SNMP->session( -hostname => 'myv3host.company.com', -version => 'snmpv3', -username => 'myv3Username', -authkey => '0x05c7fbde31916f64da4d5b77156bdfa7', -authprotocol => 'md5', -privkey => '0x93725fd3a02a48ce02df4e065a1c1746' );
if (!defined($session)) { printf("ERROR: %s.\n", $error); exit 1; }
my $sysContact = '1.3.6.1.2.1.1.4.0';
my $result = $session->set_request( -varbindlist => [$sysContact, OCTET_STRING, 'Help Desk x911'] );
if (!defined($result)) { printf("ERROR: %s.\n", $session->error); $session->close; exit 1; }
printf("sysContact for host '%s' set to '%s'\n", $session->hostname, $result->{$sysContact} );
$session->close;
exit 0;
This example gets the contents of the ifTable by sending get-bulk-requests
until the responses are no longer part of the ifTable. The ifTable can also
be retrieved using the get_table()
method.
#! /usr/local/bin/perl
use strict;
use Net::SNMP qw(:snmp);
my ($session, $error) = Net::SNMP->session( -version => 'snmpv2c', -nonblocking => 1, -hostname => shift || 'localhost', -community => shift || 'public', -port => shift || 161 );
if (!defined($session)) { printf("ERROR: %s.\n", $error); exit 1; }
my $ifTable = '1.3.6.1.2.1.2.2';
my $result = $session->get_bulk_request( -callback => [\&table_cb, {}], -maxrepetitions => 10, -varbindlist => [$ifTable] );
if (!defined($result)) { printf("ERROR: %s.\n", $session->error); $session->close; exit 1; }
snmp_dispatcher();
$session->close;
exit 0;
sub table_cb { my ($session, $table) = @_;
if (!defined($session->var_bind_list)) {
printf("ERROR: %s\n", $session->error);
} else {
# Loop through each of the OIDs in the response and assign # the key/value pairs to the anonymous hash that is passed # to the callback. Make sure that we are still in the table # before assigning the key/values.
my $next;
foreach my $oid (oid_lex_sort(keys(%{$session->var_bind_list}))) { if (!oid_base_match($ifTable, $oid)) { $next = undef; last; } $next = $oid; $table->{$oid} = $session->var_bind_list->{$oid}; }
# If $next is defined we need to send another request # to get more of the table.
if (defined($next)) {
$result = $session->get_bulk_request( -callback => [\&table_cb, $table], -maxrepetitions => 10, -varbindlist => [$next] );
if (!defined($result)) { printf("ERROR: %s\n", $session->error); }
} else {
# We are no longer in the table, so print the results.
foreach my $oid (oid_lex_sort(keys(%{$table}))) { printf("%s => %s\n", $oid, $table->{$oid}); }
} } }
This example polls several hosts for their sysUpTime using non-blocking objects and reports a warning if this value is less than the value from the last poll.
#! /usr/local/bin/perl
use strict;
use Net::SNMP qw(snmp_dispatcher ticks_to_time);
# List of hosts to poll
my @HOSTS = qw(1.1.1.1 1.1.1.2 localhost);
# Poll interval (in seconds). This value should be greater # than the number of retries plus one, times the timeout value.
my $INTERVAL = 60;
# Maximum number of polls, including the initial poll.
my $MAX_POLLS = 10;
my $sysUpTime = '1.3.6.1.2.1.1.3.0';
# Create a session for each host and queue the first get-request.
foreach my $host (@HOSTS) {
my ($session, $error) = Net::SNMP->session( -hostname => $host, -nonblocking => 0x1, # Create non-blocking objects -translate => [ -timeticks => 0x0 # Turn off so sysUpTime is numeric ] ); if (!defined($session)) { printf("ERROR: %s.\n", $error); exit 1; }
# Queue the get-request, passing references to variables that # will be used to store the last sysUpTime and the number of # polls that this session has performed.
my ($last_uptime, $num_polls) = (0, 0);
$session->get_request( -varbindlist => [$sysUpTime], -callback => [ \&validate_sysUpTime_cb, \$last_uptime, \$num_polls ] );
}
# Define a reference point for all of the polls my $EPOC = time();
# Enter the event loop snmp_dispatcher();
exit 0;
sub validate_sysUpTime_cb { my ($session, $last_uptime, $num_polls) = @_;
if (!defined($session->var_bind_list)) {
printf("%-15s ERROR: %s\n", $session->hostname, $session->error);
} else {
# Validate the sysUpTime
my $uptime = $session->var_bind_list->{$sysUpTime};
if ($uptime < ${$last_uptime}) { printf("%-15s WARNING: %s is less than %s\n", $session->hostname, ticks_to_time($uptime), ticks_to_time(${$last_uptime}) ); } else { printf("%-15s Ok (%s)\n", $session->hostname, ticks_to_time($uptime) ); }
# Store the new sysUpTime ${$last_uptime} = $uptime;
}
# Queue the next message if we have not reached $MAX_POLLS. # Since we do not provide a -callback argument, the same # callback and it's original arguments will be used.
if (++${$num_polls} < $MAX_POLLS) { my $delay = (($INTERVAL * ${$num_polls}) + $EPOC) - time(); $session->get_request( -delay => ($delay >= 0) ? $delay : 0, -varbindlist => [$sysUpTime] ); }
$session->error_status; }
David M. Town <dtown@cpan.org>
The original concept for this module was based on SNMP_Session.pm written by Simon Leinen <simon@switch.ch>.
The Abstract Syntax Notation One (ASN.1) encode and decode methods were derived by example from the CMU SNMP package whose copyright follows: Copyright (c) 1988, 1989, 1991, 1992 by Carnegie Mellon University. All rights reserved.
Copyright (c) 1998-2002 David M. Town. All rights reserved. This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.
Net::SNMP - Object oriented interface to SNMP |